=over

=item caller EXPR
X<caller> X<call stack> X<stack> X<stack trace>

=item caller

Returns the context of the current pure perl subroutine call.  In scalar
context, returns the caller's package name if there I<is> a caller (that is, if
we're in a subroutine or L<C<eval>|/eval EXPR> or
L<C<require>|/require VERSION>) and the undefined value otherwise.
caller never returns XS subs and they are skipped.  The next pure perl
sub will appear instead of the XS sub in caller's return values.  In
list context, caller returns

       # 0         1          2
    my ($package, $filename, $line) = caller;

Like L<C<__FILE__>|/__FILE__> and L<C<__LINE__>|/__LINE__>, the filename and
line number returned here may be altered by the mechanism described at
L<perlsyn/"Plain Old Comments (Not!)">.

With EXPR, it returns some extra information that the debugger uses to
print a stack trace.  The value of EXPR indicates how many call frames
to go back before the current one.

    #  0         1          2      3            4
 my ($package, $filename, $line, $subroutine, $hasargs,

    #  5          6          7            8       9         10
    $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
  = caller($i);

Here, $subroutine is the function that the caller called (rather than the
function containing the caller).  Note that $subroutine may be C<(eval)> if
the frame is not a subroutine call, but an L<C<eval>|/eval EXPR>.  In
such a case additional elements $evaltext and C<$is_require> are set:
C<$is_require> is true if the frame is created by a
L<C<require>|/require VERSION> or L<C<use>|/use Module VERSION LIST>
statement, $evaltext contains the text of the C<eval EXPR> statement.
In particular, for an C<eval BLOCK> statement, $subroutine is C<(eval)>,
but $evaltext is undefined.  (Note also that each
L<C<use>|/use Module VERSION LIST> statement creates a
L<C<require>|/require VERSION> frame inside an C<eval EXPR> frame.)
$subroutine may also be C<(unknown)> if this particular subroutine
happens to have been deleted from the symbol table.  C<$hasargs> is true
if a new instance of L<C<@_>|perlvar/@_> was set up for the frame.
C<$hints> and C<$bitmask> contain pragmatic hints that the caller was
compiled with.  C<$hints> corresponds to L<C<$^H>|perlvar/$^H>, and
C<$bitmask> corresponds to
L<C<${^WARNING_BITS}>|perlvar/${^WARNING_BITS}>.  The C<$hints> and
C<$bitmask> values are subject to change between versions of Perl, and
are not meant for external use.

C<$hinthash> is a reference to a hash containing the value of
L<C<%^H>|perlvar/%^H> when the caller was compiled, or
L<C<undef>|/undef EXPR> if L<C<%^H>|perlvar/%^H> was empty.  Do not
modify the values of this hash, as they are the actual values stored in
the optree.

Note that the only types of call frames that are visible are subroutine
calls and C<eval>. Other forms of context, such as C<while> or C<foreach>
loops or C<try> blocks are not considered interesting to C<caller>, as they
do not alter the behaviour of the C<return> expression.

Furthermore, when called from within the DB package in
list context, and with an argument, caller returns more
detailed information: it sets the list variable C<@DB::args> to be the
arguments with which the subroutine was invoked.

Be aware that the optimizer might have optimized call frames away before
L<C<caller>|/caller EXPR> had a chance to get the information.  That
means that C<caller(N)> might not return information about the call
frame you expect it to, for C<< N > 1 >>.  In particular, C<@DB::args>
might have information from the previous time L<C<caller>|/caller EXPR>
was called.

Be aware that setting C<@DB::args> is I<best effort>, intended for
debugging or generating backtraces, and should not be relied upon.  In
particular, as L<C<@_>|perlvar/@_> contains aliases to the caller's
arguments, Perl does not take a copy of L<C<@_>|perlvar/@_>, so
C<@DB::args> will contain modifications the subroutine makes to
L<C<@_>|perlvar/@_> or its contents, not the original values at call
time.  C<@DB::args>, like L<C<@_>|perlvar/@_>, does not hold explicit
references to its elements, so under certain cases its elements may have
become freed and reallocated for other variables or temporary values.
Finally, a side effect of the current implementation is that the effects
of C<shift @_> can I<normally> be undone (but not C<pop @_> or other
splicing, I<and> not if a reference to L<C<@_>|perlvar/@_> has been
taken, I<and> subject to the caveat about reallocated elements), so
C<@DB::args> is actually a hybrid of the current state and initial state
of L<C<@_>|perlvar/@_>.  Buyer beware.

=back